<!DOCTYPE html>
<!--
  ~ Copyright (c) 2017 RockScript.io.
  ~ Licensed to the Apache Software Foundation (ASF) under one
  ~ or more contributor license agreements.  See the NOTICE file
  ~ distributed with this work for additional information
  ~ regarding copyright ownership.  The ASF licenses this file
  ~ to you under the Apache License, Version 2.0 (the
  ~ "License"); you may not use this file except in compliance
  ~ with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing,
  ~ software distributed under the License is distributed on an
  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~ KIND, either express or implied.  See the License for the
  ~ specific language governing permissions and limitations
  ~ under the License.
  -->
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>RockScript Documentation</title>

  <link rel="icon" href="favicon.ico" type="image/x-icon" />

  <link rel="stylesheet" type="text/css" href="css/highlight-arduino-light-9.12.0.css">
  <link rel="stylesheet" type="text/css" href="css/rockscript-docs.css">

  <script src="js/highlight-9.12.0.js"></script>
  <script src="js/jquery-3.2.1.min.js"></script>
  <script type="application/javascript">
    $(document).ready(function() {
      $('pre code').each(function(i, block) {
        hljs.highlightBlock(block);
      });
    });
  </script>

</head>
<body>

<a href="/">
  <div class="titlebar">
    <div class="brand">RockScript.io<img alt="RockScript.io" src="img/hand-white.png"></div>
    <div class="title">RockScript Documentation</div>
  </div>
</a>

<div class="toc">
  <a href="index">Introduction</a>
  <a href="why-and-when">Why and when</a>
  <a href="how-does-it-work">How does it work</a>
  <a href="project-status">Project status</a>
  <a href="getting-started">Getting started</a>
  <a href="cli">Command line interface</a>
  <a href="tutorial">Tutorial</a>
  <a href="language">Language</a>
  <a href="script-versioning">Script versioning</a>
  <a href="license">License</a>
  <a href="roadmap">Roadmap</a>
  <a href="help">Help</a>
  <a class="title" href="services">Services</a>
  <a class="sublink" href="service-http">HTTP service</a>
  <a class="title" href="api">API</a>
  <a href="commands">Commands</a>
  <a class="sublink" href="deploy-script">Deploy script</a>
  <a class="sublink" href="start-script">Start script</a>
  <a href="queries">Queries</a>
  <a class="sublink" href="query-script-execution">Script execution</a>
  <a class="title" href="service-spi">Service SPI</a>
  <a class="sublink" href="end-function">End function</a></div>
</div>

<div class="content">
  <h1>Language</h1>
  <p>RockScript is a subset of JavaScript (ECMAScript 5.1).   The main goal of 
RockScript is to support resilient, non-blocking script execution. We aim 
to implement the most used constructs to enable the stitching of service 
functions.</p>

<p>This page documents which subset of JavaScript is supported. We leverage 
JavaScript for developers to  reduce the learning curve and it’s the perfect 
language to <a href="why-and-when#juggle-with-json">juggle with JSON</a>, which most API’s 
use these days.  But we do not aim to cover the complete language syntax. If 
you wonder why RockScript doesn’t just use Node.js, <a href="#rockscript-vs-nodejs">see at the bottom of this 
page</a>.</p>

<p>See the <a href="roadmap">Roadmap</a> for what’s next.</p>

<h2 id="system-variable">System variable</h2>
<p>The <code class="highlighter-rouge">system</code> variable is made available to every script.  It provides a mechanism 
to import activities, access the script input and (over time) other interactions 
with the runtime server environment.</p>

<h4 id="systemimport">system.import</h4>
<p>E.g.</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">var</span> <span class="nx">http</span> <span class="o">=</span> <span class="nx">system</span><span class="p">.</span><span class="k">import</span><span class="p">(</span><span class="s1">'rockscript.io/http'</span><span class="p">);</span>
</code></pre></div></div>

<p><code class="highlighter-rouge">system.import(url)</code> returns a script object that exposes activities as functions.</p>

<p>To learn about how to add activities to the engine, see <a href="services">Services</a></p>

<h4 id="systeminput">system.input</h4>

<p>When starting a script, you can pass in data.  That input data 
is made available in the script under the <code class="highlighter-rouge">system.input</code> property.</p>

<p>An example:</p>

<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>POST http://localhost:3652/command 
Content-Type: application/json
{ "startScript" : {
    "scriptId": "s726",
    "input": {
      "orderId": "9sdf8",
      "countryCode": "01" 
    }
}}
</code></pre></div></div>

<p>You can access the countryCode in the script like this:</p>

<p><code class="highlighter-rouge">var countryCode = system.input.countryCode;</code></p>

<h2 id="script-block">Script block</h2>

<p>Just like in JavaScript environments, the full script text itself is considered a block and 
the list of statements are executed sequential.</p>

<h2 id="variable-declaration">Variable declaration</h2>

<p>Examples</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">var</span> <span class="nx">variableName</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">variableName</span> <span class="o">=</span> <span class="s1">'initial value'</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">variableName</span> <span class="o">=</span> <span class="nx">system</span><span class="p">.</span><span class="k">import</span><span class="p">(</span><span class="s1">'rockscript.io/http'</span><span class="p">);</span>
</code></pre></div></div>

<h2 id="assignment">Assignment</h2>

<p>Examples</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">result</span> <span class="o">=</span> <span class="s1">'initial value'</span><span class="p">;</span>
<span class="nx">result</span><span class="p">.</span><span class="nx">message</span> <span class="o">=</span> <span class="s1">'hello'</span><span class="p">;</span>
<span class="nx">result</span><span class="p">.</span><span class="nx">message</span><span class="p">[</span><span class="s1">'firstName'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'John'</span><span class="p">;</span>
</code></pre></div></div>

<h2 id="if-then-else">If-then-else</h2>

<p>The condition expression will be converted to a boolean.  See also 
<a href="#comparison-operator-expressions">Comparison operator expressions</a> for which comparators are supported.</p>

<p>Examples</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">if</span> <span class="p">(</span><span class="nx">msg</span><span class="o">==</span><span class="s1">'call'</span><span class="p">)</span> <span class="nx">http</span><span class="p">.</span><span class="kd">get</span><span class="p">({</span><span class="na">url</span><span class="p">:</span> <span class="s1">'...'</span><span class="p">});</span>

<span class="kd">var</span> <span class="nx">someVar</span> <span class="o">=</span> <span class="p">{</span><span class="na">thisConverts</span><span class="p">:</span><span class="s1">'to boolean true'</span><span class="p">};</span>
<span class="k">if</span> <span class="p">(</span><span class="nx">someVar</span><span class="p">)</span> <span class="nx">http</span><span class="p">.</span><span class="kd">get</span><span class="p">({</span><span class="na">url</span><span class="p">:</span> <span class="s1">'...'</span><span class="p">});</span>

<span class="k">if</span> <span class="p">(</span><span class="nx">flipper</span><span class="o">===</span><span class="s1">'on'</span><span class="p">)</span> <span class="p">{</span>
  <span class="nx">http</span><span class="p">.</span><span class="kd">get</span><span class="p">({</span><span class="na">url</span><span class="p">:</span> <span class="s1">'...'</span><span class="p">});</span>
  <span class="nx">flipper</span> <span class="o">=</span> <span class="s1">'off'</span><span class="p">;</span>
<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
  <span class="nx">flipper</span> <span class="o">=</span> <span class="s1">'on'</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>

<h2 id="loops">Loops</h2>

<p>For now, only 1 form of loop is supported.</p>

<p>Example</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">for</span> <span class="p">(</span><span class="kd">var</span> <span class="nx">i</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="nx">i</span><span class="o">&lt;</span><span class="nx">a</span><span class="p">.</span><span class="nx">length</span><span class="p">;</span> <span class="nx">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
  <span class="nx">total</span> <span class="o">=</span> <span class="nx">total</span> <span class="o">+</span> <span class="nx">a</span><span class="p">[</span><span class="nx">i</span><span class="p">];</span>
<span class="p">}</span>
</code></pre></div></div>

<blockquote>
  <p>Limitation: Other forms of loops are not yet supported like <code class="highlighter-rouge">do while</code>, <code class="highlighter-rouge">while do</code>, <code class="highlighter-rouge">for (non-var-declaring-expression;...;...)</code>, <code class="highlighter-rouge">for (a in b)</code> and <code class="highlighter-rouge">for (var a in b)</code></p>
</blockquote>

<h2 id="default-functions-and-properties">Default functions and properties</h2>

<p>Strings and arrays do not have any predefined functions and properties except for property <code class="highlighter-rouge">length</code>.</p>

<p>Example</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">var</span> <span class="nx">a</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">];</span>
<span class="k">for</span> <span class="p">(</span><span class="kd">var</span> <span class="nx">i</span><span class="o">=</span><span class="mi">0</span><span class="p">;</span> <span class="nx">i</span><span class="o">&lt;</span><span class="nx">a</span><span class="p">.</span><span class="nx">length</span><span class="p">;</span> <span class="nx">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
  <span class="nx">total</span> <span class="o">=</span> <span class="nx">total</span> <span class="o">+</span> <span class="nx">a</span><span class="p">[</span><span class="nx">i</span><span class="p">];</span>
<span class="p">}</span>
</code></pre></div></div>

<h2 id="declaring-functions">Declaring functions</h2>

<p>At the moment we don’t support declaration of functions in the script.  We’re believe it’s best to leave 
out functions so that each script remains the scope of 1 function.  But this is still a hypothesis that 
we’re seeking validation on.  So <a href="https://github.com/rockscript/rockscript/issues/new?title=Function+declarations">your input</a> 
is greatly appreciated.</p>

<h2 id="expressions">Expressions</h2>

<h4 id="literals">Literals</h4>

<p>Examples</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="s1">'some text'</span>
<span class="mi">1</span>
<span class="mf">5.0</span>
<span class="kc">true</span>
<span class="kc">false</span>
<span class="p">{</span> <span class="nl">country</span><span class="p">:</span> <span class="s1">'US'</span> <span class="p">}</span>
<span class="p">[</span> <span class="s1">'a'</span><span class="p">,</span> <span class="s1">'b'</span><span class="p">,</span> <span class="s1">'c'</span><span class="p">]</span>
</code></pre></div></div>

<h4 id="variable-expressions">Variable expressions</h4>
<p>Examples</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">variableName</span>
<span class="nx">variableName</span><span class="p">.</span><span class="nx">propertName</span><span class="p">;</span>
<span class="nx">variableName</span><span class="p">.</span><span class="nx">propertyName</span><span class="p">(</span><span class="nx">arg0</span><span class="p">,</span> <span class="nx">arg1</span><span class="p">);</span>
<span class="nx">variableName</span><span class="p">[</span><span class="nx">propertyName</span><span class="p">];</span>
</code></pre></div></div>
<p>Or a combination of the above like eg</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>variableName.propertyName(arg0, arg1)['field'].anotherPropertyName;
</code></pre></div></div>
<p>Note that for service function invocations, any number of args is allowed.</p>

<h4 id="comparison-operators">Comparison operators</h4>

<p>All of <a href="https://developer.mozilla.org/nl/docs/Web/JavaScript/Equality_comparisons_and_sameness">Equality comparisons and sameness</a> 
is implemented</p>

<blockquote>
  <p>Limitation: While all automatic type conversions are implemented, object conversion functions like <code class="highlighter-rouge">toString </code> and <code class="highlighter-rouge">valueOf</code> are not invoked yet.</p>
</blockquote>

<p>Examples</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nx">text</span><span class="o">==</span><span class="s1">'some text'</span>
<span class="s1">'25'</span> <span class="o">!=</span> <span class="nx">service</span><span class="p">.</span><span class="nx">getSomeNumber</span><span class="p">()</span>
<span class="nx">text</span><span class="o">===</span><span class="s1">'some text'</span>
<span class="mi">5</span> <span class="o">&lt;</span> <span class="nx">totalAmount</span>
<span class="kc">true</span> <span class="o">&gt;</span> <span class="mi">0</span>
<span class="nx">customer</span><span class="p">.</span><span class="nx">getAge</span><span class="p">()</span> <span class="o">&lt;=</span> <span class="mi">25</span>
<span class="s1">'hello'</span> <span class="o">&gt;=</span> <span class="nx">company</span><span class="p">.</span><span class="nx">getName</span><span class="p">()</span>
</code></pre></div></div>

<h4 id="arithmic-operators">Arithmic operators</h4>

<p>All the addition conversions are correctly applied like in Node.js</p>

<p>Supported: <code class="highlighter-rouge">+</code>, <code class="highlighter-rouge">-</code>, <code class="highlighter-rouge">*</code>, <code class="highlighter-rouge">/</code>, <code class="highlighter-rouge">++</code>, <code class="highlighter-rouge">--</code></p>

<p>Examples</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="s1">'hello'</span> <span class="o">+</span> <span class="s1">' world'</span> 
<span class="mi">5</span> <span class="o">+</span> <span class="s1">' EUR'</span>
<span class="s1">'Formula '</span> <span class="o">+</span> <span class="kc">true</span>
<span class="nx">count</span> <span class="o">*</span> <span class="mi">5</span>
<span class="nx">i</span><span class="o">++</span>
</code></pre></div></div>

<blockquote>
  <p>Limitations: <code class="highlighter-rouge">%</code> and <code class="highlighter-rouge">**</code> are not yet supported.<br />
And for the conversions, while all automatic type 
conversions are implemented, object conversion functions like <code class="highlighter-rouge">toString </code> and <code class="highlighter-rouge">valueOf</code> are 
not invoked yet.</p>
</blockquote>

<h4 id="logical-operators-and-parenthesis">Logical operators and parenthesis</h4>

<p>Examples</p>
<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="o">!</span><span class="p">(</span><span class="kc">true</span> <span class="o">||</span> <span class="kc">false</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="kc">true</span>
</code></pre></div></div>

<h2 id="rockscript-vs-nodejs">RockScript vs Node.js</h2>

<p>The purpose of RockScript is resilient script execution.  In order to do this, we 
need continuations.  This means that need the ability to serialize the complete 
runtime state of a script execution when the script is waiting for external 
callbacks.  And when the server gets a callback, we need to restore the 
runtime state from the persisted state and then resume execution at that 
position in the script.  Serializing and deserializing execution state 
and resuming an execution after deserializing it is something that other 
script engines can’t do so that’s why we created RockScript.</p>


</div>

</body>
</html>
